3D Graphics Programming with QuickDraw 3D 1.5.4

Renderer-Private Data in Draw Regions

A renderer may attach private data to a draw region; for example, a Z-buffer renderer can attach its Z buffer to the draw region instead of maintaining it elsewhere.

To attach data, the renderer uses the Q3XDrawRegion_SetRendererPrivate function. It must provide an opaque pointer to the data (or data structure), as well as provide a method to be used by the draw region to dispose of the data; this function is called when the draw region is itself disposed. Thus the renderer is responsible for providing the callback so that the attached data will properly be disposed of.

To retrieve data previously attached to a draw region, a renderer can use the Q3XDrawRegion_GetRendererPrivate function. Note that this merely returns the pointer provided in the Q3XDrawRegion_SetRendererPrivate call; it does not remove the need for a disposal callback.

Q3XDrawRegion_SetRendererPrivate

The Q3XDrawRegion_SetRendererPrivate function attaches renderer-private data to a draw region.



 
typedef void (*TQ3XDrawRegionRendererPrivateDeleteMethod)(

                     void    *rendererPrivate);



 
TQ3Status Q3XDrawRegion_SetRendererPrivate(

                     TQ3XDrawRegion    drawRegion,

                     const void        *rendererPrivate,

                     TQ3XDrawRegionRendererPrivateDeleteMethod    deleteMethod);

drawRegion: A draw region.
rendererPrivate: Pointer to private data.
deleteMethod: Private data disposal method.

DESCRIPTION

The Q3XDrawRegion_SetRendererPrivate function attaches the private data pointed to by the rendererPrivate parameter to the draw region designated by the drawRegion parameter. It also registers the data disposal method designated by deleteMethod. The draw region will call this method to dispose of the private data when it is itself disposed of.

Q3XDrawRegion_GetRendererPrivate

The Q3XDrawRegion_GetRendererPrivate functionality lets a renderer retrieve private data that was previously attached to a draw region by using the Q3XDrawRegion_SetRendererPrivate routine.



 
TQ3Status Q3XDrawRegion_GetRendererPrivate(

                     TQ3XDrawRegion    drawRegion,

                     void              **rendererPrivate);

drawRegion: A draw region.
rendererPrivate: On return, a pointer to the private data attached to the draw region designated by drawRegion.

DESCRIPTION

The Q3XDrawRegion_GetRendererPrivate function returns, in the rendererPrivate parameter, the pointer to private data that was passed in a previous call to Q3XDrawRegion_SetRendererPrivate.